<!doctype html>
<html lang="en" class="page-type-section">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>escape, noescape - FreeMarker 手册</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker 手册">
<meta property="og:title" content="escape, noescape">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://freemarker.org/docs/ref_directive_escape.html">
<link rel="canoical" href="http://freemarker.org/docs/ref_directive_escape.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css">
</head>
<body itemscope itemtype="https://schema.org/Code">
    <meta itemprop="url" content="http://freemarker.org/docs/">
    <meta itemprop="name" content="FreeMarker 手册">

  <!--[if lte IE 9]>
  <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
  <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org" role="banner">            <img itemprop="image" src="logo.png" alt="FreeMarker">
</a><ul class="tabs"><li><a href="http://freemarker.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="http://freemarker.org/docs/api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://sourceforge.net/p/freemarker/bugs/new/" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="toc.html" class="navigation-header">Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="toc.html"><span itemprop="name">FreeMarker 手册</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref.html"><span itemprop="name">模板语言参考 </span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directives.html"><span itemprop="name">指令参考</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directive_escape.html"><span itemprop="name">escape, noescape</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div>    <div class="main-content site-width">
      <div class="content-wrapper">
  <div id="table-of-contents-wrapper" class="col-left">
      <script>var breadcrumb = ["FreeMarker 手册","模板语言参考 ","指令参考","escape, noescape"];</script>
      <script src="toc.js"></script>
      <script src="docgen-resources/main.min.js"></script>
  </div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="ref_directive_compress.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_flush.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="ref_directive_escape" itemprop="headline">escape, noescape</h1>
</div></div><div class="page-menu">
<div class="page-menu-title">Page Contents</div>
<ul><li><a class="page-menu-link" href="#autoid_75" data-menu-target="autoid_75">概要</a></li><li><a class="page-menu-link" href="#autoid_76" data-menu-target="autoid_76">描述</a></li></ul> </div><a name="ref.directive.escape"></a><a name="ref.directive.noescape"></a>
          



<h2 class="content-header header-section2" id="autoid_75">概要</h2>


          
<pre class="metaTemplate">
<code class="inline-code">&lt;#escape <em class="code-color">identifier</em> as <em class="code-color">expression</em>&gt;
  <em class="code-color">...</em>
  &lt;#noescape&gt;<em class="code-color">...</em>&lt;/#noescape&gt;
  <em class="code-color">...</em>
&lt;/#escape&gt;</code>
</pre>

        
          



<h2 class="content-header header-section2" id="autoid_76">描述</h2>


          <p>当你使用escape指令包围模板中的一部分时，在块中出现的插值
		  (<code class="inline-code">${<em class="code-color">...</em>}</code>) 
		  会和转义表达式自动结合。这是一个避免编写相似表达式的很方便的方法。
		  它不会影响在字符串形式的插值(比如在 <code class="inline-code">&lt;#assign x =
          &quot;Hello ${user}!&quot;&gt;</code>)。而且，它也不会影响数值插值
		  (<code class="inline-code">#{<em class="code-color">...</em>}</code>)。</p>

          <p>例如：</p>

          

<div class="code-wrapper"><pre class="code-block code-template"><strong>&lt;#escape x as x?html&gt;</strong>
  First name: ${firstName}
  Last name: ${lastName}
  Maiden name: ${maidenName}
<strong>&lt;/#escape&gt;</strong></pre></div>

          <p>事实上它等同于：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">  First name: ${firstName<strong>?html</strong>}
  Last name: ${lastName<strong>?html</strong>}
  Maiden name: ${maidenName<strong>?html</strong>}</pre></div>

          <p>请注意，它和你在指令中用什么样的标识符无关 - 
		  它仅仅是作为一个转义表达式的正式参数。</p>

          <p>当在调用宏或者 <code class="inline-code">include</code> 指令时，
		  理解 <em>在模板文本</em> 中转义仅仅对出现在 <code class="inline-code">&lt;#escape
          <em class="code-color">...</em>&gt;</code> 和 
		  <code class="inline-code">&lt;/#escape&gt;</code> 中的插值起作用是很重要的。
		  也就是说，它不会转义文本中 
		  <code class="inline-code">&lt;#escape <em class="code-color">...</em>&gt;</code> 
		  之前的东西或 <code class="inline-code">&lt;/#escape&gt;</code> 之后的东西，
		  也不会从 <code class="inline-code">escape</code> 的部分中来调用。</p>

          

<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign x = &quot;&lt;test&gt;&quot;&gt;
&lt;#macro m1&gt;
  m1: ${x}
&lt;/#macro&gt;
&lt;#escape x as x?html&gt;
  &lt;#macro m2&gt;m2: ${x}&lt;/#macro&gt;
  ${x}
  &lt;@m1/&gt;
&lt;/#escape&gt;
${x}
&lt;@m2/&gt;</pre></div>

          <p>将会输出：</p>

          

<div class="code-wrapper"><pre class="code-block code-output">  &amp;lt;test&amp;gt;
  m1: &lt;test&gt;
&lt;test&gt;
m2: &amp;lt;test&amp;gt;</pre></div>

          <p><span class="marked-for-programmers">从更深的技术上说，
		  <code class="inline-code">escape</code> 指令的作用是用在模板解析的时间而不是模板处理的时间。
		  这就表示如果你调用一个宏或从一个转义块中包含另外一个模板，
		  它不会影响在宏/被包含模板中的插值，因为宏调用和模板包含被算在模板处理时间。
		  另外一方面，如果你用一个转义区块包围一个或多个宏声明(算在模板解析时间，和宏调用想法)，
		  那么那些宏中的插值将会和转义表达式合并。</span></p>

          <p>有时需要暂时为一个或两个在转义区块中的插值关闭转义。你可以通过关闭，
		  过后再重新开启转义区块来达到这个功能，但是那么你不得不编写两遍转义表达式。
		  你可以使用非转义指令来替代：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">&lt;#escape x as x?html&gt;
  From: ${mailMessage.From}
  Subject: ${mailMessage.Subject}
  <strong>&lt;#noescape&gt;</strong>Message: ${mailMessage.htmlFormattedBody}<strong>&lt;/#noescape&gt;</strong>
  <em>...</em>
&lt;/#escape&gt;</pre></div>

          <p>和这个是等同的：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">  From: ${mailMessage.From?html}
  Subject: ${mailMessage.Subject?html}
  Message: ${mailMessage.htmlFormattedBody}
  ...</pre></div>

          <p>转义可以被嵌套(尽管你不会在罕见的情况下来做)。
		  因此，你可以编写如下面代码(这个例子固然是有点伸展的，
		  正如你可能会使用 <code class="inline-code">list</code> 来迭代序列中的每一项，
		  但是我们现在所做的是阐述这个观点)的东西：</p>

          

<div class="code-wrapper"><pre class="code-block code-template"><strong>&lt;#escape x as x?html&gt;</strong>
  Customer Name: ${customerName}
  Items to ship:
  <strong>&lt;#escape x as itemCodeToNameMap[x]&gt;</strong>
    ${itemCode1}
    ${itemCode2}
    ${itemCode3}
    ${itemCode4}
  <strong>&lt;/#escape&gt;</strong>
<strong>&lt;/#escape&gt;</strong></pre></div>

          <p>实际上和下面是等同的：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">  Customer Name: ${customerName?html}
  Items to ship:
    ${itemCodeToNameMap[itemCode1]?html}
    ${itemCodeToNameMap[itemCode2]?html}
    ${itemCodeToNameMap[itemCode3]?html}
    ${itemCodeToNameMap[itemCode4]?html}</pre></div>

          <p>当你在嵌入的转义区块内使用非转义指令时，它仅仅不处理一个单独层级的转义。
		  因此，为了在两级深的转义区块内完全关闭转义，你需要使用两个嵌套的非转义指令。</p>
        <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_directive_compress.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_flush.html"><span>Next</span></a></div></div></div></div>      </div>
    </div>
<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/index.html">What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html">About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/nanlei/freemarker/tree/manual-zh-2.3-gae/src/manual">Chinese Manual on Github</a></li><li><a href="https://github.com/freemarker/freemarker">FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker">Follow us on Twitter</a></li><li><a href="https://sourceforge.net/p/freemarker/bugs/new/">Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker">Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html">Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"><p><span class="generated-for-product">Generated for: Freemarker 2.3.23</span><span class="last-updated"> Last generated:
<time itemprop="dateModified" datetime="2015-09-18T14:38:51Z" title="Friday, September 18, 2015 2:38:51 PM GMT">2015-09-18 14:38:51 GMT</time></span></p> <p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2015
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="http://freemarker.org">The FreeMarker Project</a>. All rights reserved. </p>
</div></div></div></body>
</html>
